shoulder, bicep, elbow, arm
forearm, thumb, wrist, knuckle, palm
middle, pinky, index, ring
dinner bell dinner bell ding
(They Might Be Giants, "Dinner Bell")

Invoking hsc

General rules

As hsc is an tool developed under AmigaOS and I never liked the cryptic "cmd -cvf -osepp.x"-way of invoking commands comming from Unix, hsc uses a syntax like most commands of AmigaOS; even for ports on other operating-systems.

All options and swiches are case-insensitive. If you start hsc without any options, a short help message will be displayed.

Options require an additional argument, for example a file. All of the below terms are treated as the same: FILE hugo.hsc, file hugo.hsc or file=hugo.hsc.

Switches are enabled if their keyword is detected within the command-line.

If you still don't understand this, get a manual for AmigaOS.

Options

HELP

Display a short help message and exit.

LICENSE

Display a short version of the GNU General Public License and exit.

[FROM=]inputfile-name

Specifies the input filename. To use stdin as input file, the peudo-filename STDIN (case sensitive) should be specified. If you specify more than one file, the last file is taken as mainfile, and all previous files are included before it. This is useful to include macro-definitions within the command-line instead of an <$include> in the hsc-source.

TO=output-filename|destination-directory

Specifies the output filename or the destination directory. If the argument ends with a "/" (or also ":"), it is interpreted as a directory. In this case, the name of the outputfile is created from the name of the input file, with an extension specified (see below).
If no output file is set, stdout is used instead.

EXTENSION=output-extension

If you specify a directory for output, the output-filename will depend on the input-filename and the extension specified with this options. If you do not set an extension, "html" will be used. A period (`.') will be added automatically. Setting EXTENSION=. will ommit this and result into exactly the same filename as the input. If you specify a complete filename for output, this option has no effect.

MSGFILE=message-filename

Redirects messages to a file. By default, stderr ist used.

MSGFORMAT=format-description

Describes how messages should be displayed. Legal placeholders:

        %f      filename
        %x, %y  location in file (column, line)
        %c      message class
        %i      message id (numeric)
        %m      message text
        %n      inserts a linefeed

Example: To get GCC-like messages, use MSGFORMAT="%f:%y: %c %i: %m".

PREFSFILE=preferences-filename

Specifies filename for sytax-definition to be used, if you don't want to use the defaults.

PRJFILE=project-filename

Stores some information about the document currently processing in a seperate file to extend functionality. Read the section about Project managment for more details. Note that all documents within a project should use the same project-file.

DEFINE

Defines a global attribute. The syntax is equal to <$define>, exept that you need no quotes surrounding the value.
Example: DEFINE "hugo:string=hugo was here"

IGNORE

Ignore warning message number. Usually, IGNORE needs a numeric argument and can occure multiple. Example:

        IGNORE=21 IGN=18 IGN 3         (ignore warnings #21, #18, #3)

Additionally, you can give IGNORE some special values:

ALL: Ignore all non-error messages
NOTES: Ignore all notes
BADSTYLE: Ignore all bad style warnings

All these special values add new messages to the list of messages to be ignored, but do not reset any IGNOREs passed before.

MODE

Set base mode for syntax check. Legal values are PEDANTIC, NORMAL and RELAXED. Default is NORMAL. This only disables several messages and warnings from the beginning. Any IGNOREs passed before are reseted.

QUOTESTYLE

Specifies which kind of quotes should be used to surround attribute-values. KEEP keeps the user-kind, DOUBLE tries to assign double quotes (eg. "value"), SINGLE tries to assign single quotes (eg. 'value') and NONE will remove quotes if possible.

STATUS

Display several status messages (output goes to stderr). Legal flags are:

QUIET: no status messages
LINE: display name and line of file currently processing Included files are also displayed. After processing a file, the filename and the total number of lines remain visible.
VERSION: display program title and version
VERBOSE: enable verbose status messages; this includes the information displayed during the processing of <$exec> and some details about images, if GETSIZE has also been enabled.
FULL: enable all status messages

The above flags can be combined by separating them with a vertical bar (`|'), eg STATUS=line|version, exept for QUIET and FULL

STRIPTAGS=tag-list

Strip some specific tags from document. tag-list is a string, that contains all tags that should be stripped, sepparated by a vertical bar (`|').
See also STRIPCOMMENT and STRIPEXTERNAL.

ICONBASE=base-uri

Replace all icon-entities by images that must be available in base-uri. For example, with ICONBASE=:icons, the entity &back; is replaced by <IMG SRC=":icons/back.gif" ALT="back">. Note that this argument does not denote a directory, but an URI. It's recommended to use an absolute URI. If you don't want to use *.gif-files for your icon-entities, you can use an asterisk (`*') to be replaced by the name of the icon-entity; eg. ICONBASE=:icons/*.png.

Switches

COMPACT: Strip redundant linefeeds and white-spaces from output.
-DEBUG: If you've compiled hsc in debug-mode, it will send lots of information to stderr. Otherwise, this option is equivalent to STATUS=FULL.
GETSIZE: Get width and height of images and set corresponding attributes WIDTH and HEIGHT with these values;
MSGANSI: Uses ansi-sequences to make messages more readable.
RPLCENT: Replace special characters with its entity (eg `ü' becomes `&uuml').
RPLCQUOTE: Replace double-quotes (`"') found in the text by ". This does not affect quotes used inside attribute-values.
SMARTENT: Replace special characters `&", `<' and `>' with their entities (&, < and >) if they are surrounded by white-spaces.
STRIPCOMMENT: Strip all SGML-comments from input.
STRIPEXTERNAL: Strip tags which refer to an external URI.

Thomas Aglassinger (agi@giga.or.at), 30-Sep-1996